#include <dataframe.h>

Classes
struct	params

Public Types
using	examples_t = std::vector<src::example>
using	value_type = examples_t::value_type
using	iterator = examples_t::iterator
using	const_iterator = examples_t::const_iterator
using	difference_type = examples_t::difference_type

Public Member Functions
	dataframe (std::istream &)
	dataframe (std::istream &, const params &)
	dataframe (const std::filesystem::path &)
	dataframe (const std::filesystem::path &, const params &)
template<DataframeMatrix R>
	dataframe (const R &)
template<DataframeMatrix R>
	dataframe (const R &, params)
iterator	begin () noexcept
const_iterator	begin () const noexcept
iterator	end () noexcept
const_iterator	end () const noexcept
const value_type &	front () const
value_type &	front ()
void	clear ()
iterator	erase (iterator, iterator)
void	push_back (src::example, bool=false)
template<std::input_iterator InputIt>
iterator	insert (const_iterator, InputIt, InputIt)
void	swap (dataframe &)
std::size_t	read (const std::filesystem::path &)
std::size_t	read (const std::filesystem::path &, const params &)
std::size_t	read (std::istream &)
std::size_t	read (std::istream &, params)
template<DataframeMatrix R>
std::size_t	read (const R &)
template<DataframeMatrix R>
std::size_t	read (const R &, params)
bool	operator! () const noexcept
bool	clone_schema (const dataframe &)
bool	set_schema (const std::vector< std::pair< std::string, domain_t > > &)
std::size_t	size () const noexcept
bool	empty () const noexcept
class_t	classes () const noexcept
unsigned	variables () const
std::string	class_name (class_t) const noexcept
task_t	task () const noexcept
bool	is_valid () const
template<std::ranges::range R>
example	to_example (const R &r) const
template<DataframeRow R>
bool	read_record (R r, std::optional< std::size_t > output_index, bool add_instance)
template<DataframeMatrix R>
std::size_t	read (const R &container, params p)
template<DataframeMatrix R>
std::size_t	read (const R &container)
template<DataframeMatrix R>
	dataframe (const R &t, params p)
template<DataframeMatrix R>
	dataframe (const R &t)

Public Attributes
src::columns_info	columns {}

Related Symbols
(Note that these are not member symbols.)
std::ostream &	operator<< (std::ostream &os, const dataframe &d)

Detailed Description

Owning container for tabular data and its schema.

The dataframe class provides a uniform interface to load, store and validate datasets coming from files, streams or in-memory ranges.

See also: https://github.com/morinim/ultra/wiki/dataframe

Constructor & Destructor Documentation

◆ dataframe() [1/6]

ultra::src::dataframe::dataframe	(	std::istream &	is,
		const params &	p )

New dataframe instance containing the learning collection from a stream.

Parameters

[in]	is	input stream
[in]	p	additional, optional, parameters (see params structure)

Note: Data from the input stream can be in either CSV or XRFF format.

◆ dataframe() [2/6]

ultra::src::dataframe::dataframe	(	const std::filesystem::path &	fn,
		const params &	p )

New dataframe instance containing the learning collection from a file.

Parameters

[in]	fn	name of the file containing the learning collection (CSV / XRFF format)
[in]	p	additional, optional, parameters (see params structure)

Note: Data from the input stream can be in either CSV or XRFF format.

◆ dataframe() [3/6]

template<DataframeMatrix R>

ultra::src::dataframe::dataframe ( const R & t )

Construct a dataframe from a matrix-like range.

Template Parameters

R	a DataframeMatrix type

Parameters

[in] t the data source

Remarks: The first row of the table must contain headers.

◆ dataframe() [4/6]

template<DataframeMatrix R>

ultra::src::dataframe::dataframe	(	const R &	t,
		params	p )

Construct a dataframe from a matrix-like range.

Template Parameters

R	a DataframeMatrix type

Parameters

[in]	t	the data source
[in]	p	additional, optional, parameters (see params structure)

Remarks: The first row is interpreted as column headers unless overridden via parameters.

◆ dataframe() [5/6]

template<DataframeMatrix R>

ultra::src::dataframe::dataframe	(	const R &	t,
		params	p )

Construct a dataframe from a matrix-like range.

Template Parameters

R	a DataframeMatrix type

Parameters

[in]	t	the data source
[in]	p	additional, optional, parameters (see params structure)

Remarks: The first row is interpreted as column headers unless overridden via parameters.

◆ dataframe() [6/6]

template<DataframeMatrix R>

ultra::src::dataframe::dataframe ( const R & t )

Construct a dataframe from a matrix-like range.

Template Parameters

R	a DataframeMatrix type

Parameters

[in] t the data source

Remarks: The first row of the table must contain headers.

Member Function Documentation

◆ begin() [1/2]

dataframe::const_iterator ultra::src::dataframe::begin ( ) const

nodiscardnoexcept

Returns: a constant reference to the first element of the dataset

◆ begin() [2/2]

dataframe::iterator ultra::src::dataframe::begin ( )

nodiscardnoexcept

Returns: reference to the first element of the active dataset

◆ class_name()

std::string ultra::src::dataframe::class_name ( class_t i ) const

nodiscardnoexcept

Retrieve the external name of a class.

Parameters

[in] i internal class identifier

Returns: human-readable name associated with the class (or an empty string if such class cannot be find)

◆ classes()

class_t ultra::src::dataframe::classes ( ) const

nodiscardnoexcept

Returns: number of classes of the problem (== 0 for a symbolic regression problem, > 1 for a classification problem)

◆ clear()

void ultra::src::dataframe::clear ( )

Removes all elements from the container.

Invalidates any references, pointers or iterators referring to contained examples. Any past-the-end iterators are also invalidated.

Leaves the associated metadata unchanged.

◆ clone_schema()

bool ultra::src::dataframe::clone_schema ( const dataframe & other )

Creates a copy of a given schema in an empty dataframe.

Parameters

[in] other dataframe we copy schema from

Returns: true if schema has been cloned

Warning: If the current dataframe isn't empty the operation fails.

◆ empty()

bool ultra::src::dataframe::empty ( ) const

nodiscardnoexcept

Returns: true if the dataframe is empty

◆ end() [1/2]

dataframe::const_iterator ultra::src::dataframe::end ( ) const

nodiscardnoexcept

Returns: a constant reference to the sentinel element of the active dataset

◆ end() [2/2]

dataframe::iterator ultra::src::dataframe::end ( )

nodiscardnoexcept

Returns: a reference to the sentinel element of the active dataset

◆ erase()

dataframe::iterator ultra::src::dataframe::erase	(	iterator	first,
		iterator	last )

Removes specified elements from the dataframe.

Parameters

[in]	first	first element of the range
[in]	last	end of the range

Returns: iterator following the last removed element

◆ front() [1/2]

dataframe::value_type & ultra::src::dataframe::front ( )

nodiscard

Returns a reference to the first element in the dataframe.

Returns: a reference to the first element in the dataframe

Remarks: Calling front on an empty dataframe is undefined.

◆ front() [2/2]

const dataframe::value_type & ultra::src::dataframe::front ( ) const

nodiscard

Returns a constant reference to the first element in the dataframe.

Returns: a constant reference to the first element int the dataframe

Remarks: Calling front on an empty dataframe is undefined.

◆ insert()

template<std::input_iterator InputIt>

dataframe::iterator ultra::src::dataframe::insert	(	dataframe::const_iterator	pos,
		InputIt	first,
		InputIt	last )

Inserts elements from range [first, last[ before pos.

Parameters

[in]	pos	iterator before which the content will be inserted (may be the end() iterator)
[in]	first	first iterator of the range of elements to insert, cannot be iterator into container for which insert is called
[in]	last	last iterator of the range of elements to insert, cannot be iterator into container for which insert is called

Returns: iterator pointing to the first element inserted, or pos if first == last

Remarks: If, after the operation, the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all references to the elements are invalidated; otherwise, only the iterators and references before the insertion point remain valid.

◆ is_valid()

bool ultra::src::dataframe::is_valid ( ) const

nodiscard

Returns: true if the object passes the internal consistency check

◆ operator!()

bool ultra::src::dataframe::operator! ( ) const

nodiscardnoexcept

Returns: true if the current dataset is empty

◆ push_back()

void ultra::src::dataframe::push_back	(	src::example	e,
		bool	add_instance = false )

Appends the given element to the end of the active dataset.

Parameters

[in]	e	the value of the element to append
[in]	add_instance	should we automatically add instances for text features?

◆ read() [1/3]

template<DataframeMatrix R>

std::size_t ultra::src::dataframe::read	(	const R &	container,
		params	p )

Populate the dataframe from an in-memory range.

Parameters

[in]	container	the input data
[in]	p	parsing and typing parameters. Only p.data_typing and p.output_index are used

Returns: the number of rows stored in the dataframe (0 in case of error)

This function clears existing data, infers the schema using columns_info::build and then loads all rows into the dataframe.

◆ read() [2/3]

template<DataframeMatrix R>

std::size_t ultra::src::dataframe::read	(	const R &	container,
		params	p )

Populate the dataframe from an in-memory range.

Parameters

[in]	container	the input data
[in]	p	parsing and typing parameters. Only p.data_typing and p.output_index are used

Returns: the number of rows stored in the dataframe (0 in case of error)

This function clears existing data, infers the schema using columns_info::build and then loads all rows into the dataframe.

◆ read() [3/3]

std::size_t ultra::src::dataframe::read	(	const std::filesystem::path &	fn,
		const params &	p )

Loads the content of a file into the active dataset.

Parameters

[in]	fn	name of the file containing the data set (CSV / XRFF format)
[in]	p	additional, optional, parameters (see params structure)

Returns: number of lines parsed

Exceptions

std::invalid_argument missing dataset file name

Note: Test set can have an empty output value.

◆ read_record()

template<DataframeRow R>

bool ultra::src::dataframe::read_record	(	R	r,
		std::optional< std::size_t >	output_index,
		bool	add_instance )

Parameters

[in]	r	an example in raw format
[in]	output_index	index of the output column
[in]	add_instance	should we automatically add instances for text features?

Returns: true for a correctly converted/imported record

◆ set_schema()

bool ultra::src::dataframe::set_schema ( const std::vector< std::pair< std::string, domain_t > > & schema )

Sets the schema of the dataframe.

Parameters

[in] schema the dataframe schema

Returns: true if schema has been set

Warning: If the current dataframe isn't empty the operation fails.

◆ size()

std::size_t ultra::src::dataframe::size ( ) const

nodiscardnoexcept

Returns: the size of the active dataset

◆ swap()

void ultra::src::dataframe::swap ( dataframe & other )

Exchanges the contents and capacity of the container with those of other.

Parameters

[in] other dataframe to exchange the contents with

Remarks: All iterators and references remain valid. The end() iterator is invalidated.

◆ task()

task_t ultra::src::dataframe::task ( ) const

nodiscardnoexcept

Return the learning task associated with the dataframe.

Returns: the inferred or configured task type

The task reflects the role and domain of the output column and may be classification, regression or unsupervised learning.

◆ to_example()

template<std::ranges::range R>

example ultra::src::dataframe::to_example ( const R & r ) const

Parameters

[in] r a range containing the example

Returns: r converted to example type

◆ variables()

unsigned ultra::src::dataframe::variables ( ) const

nodiscard

Return the number of input variables.

Returns: the number of columns used as input variables

Note: Output columns are excluded from this count (if the dataset is not empty, variables() + 1 == columns.size()).

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	os,
		const dataframe &	d )

Prints the content of the dataframe on a given stream (markdown format).

Parameters

[out]	os	output stream
[in]	d	dataframe to be printed

Returns: a reference to the (updated) output stream

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Public Attributes

Related Symbols

Detailed Description

Constructor & Destructor Documentation

◆ dataframe() [1/6]

◆ dataframe() [2/6]

◆ dataframe() [3/6]

◆ dataframe() [4/6]

◆ dataframe() [5/6]

◆ dataframe() [6/6]

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ class_name()

◆ classes()

◆ clear()

◆ clone_schema()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase()

◆ front() [1/2]

◆ front() [2/2]

◆ insert()

◆ is_valid()

◆ operator!()

◆ push_back()

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ read_record()

◆ set_schema()

◆ size()

◆ swap()

◆ task()

◆ to_example()

◆ variables()

Friends And Related Symbol Documentation

◆ operator<<()