Given two vector spaces, \( \texttip{\mathcal{X}}{Polish sample vector space} \subseteq \mathbb{R}^{d_x} \) and \( \texttip{\mathcal{Y}}{Polish sample vector space} \subseteq \mathbb{R}^{d_y} \), and a map \( f: \mathcal{X} \to \mathcal{Y} \), the Estimator's goal is to produce a model \( f^*:\mathcal{X} \to \mathcal{Y} \) that best approximates \( f \). More...

#include <Estimator.h>

Inheritance diagram for lucid::Estimator:

Public Member Functions
	Estimator (Parameters parameters=NoParameters, const std::shared_ptr< const Tuner > &tuner=nullptr)
	Construct a new Estimator object.

Matrix	operator() (ConstMatrixRef x) const
	A model is a function that takes a \( n \times d_x \) matrix of row vectors in the input space \( \mathcal{X} \) and returns a \( n \times d_y \) matrix of row vectors in the output space \( \mathcal{Y} \).

virtual Matrix	predict (ConstMatrixRef x) const =0
	A model is a function that takes a \( n \times d_x \) matrix of row vectors in the input space \( \mathcal{X} \) and returns a \( n \times d_y \) matrix of row vectors in the output space \( \mathcal{Y} \).

Estimator &	fit (ConstMatrixRef training_inputs, ConstMatrixRef training_outputs, const Tuner &tuner)
	Fit the model to the given data.

Estimator &	fit (ConstMatrixRef training_inputs, ConstMatrixRef training_outputs)
	Fit the model to the given data.

Estimator &	fit_online (ConstMatrixRef training_inputs, const OutputComputer &training_outputs, const Tuner &tuner)
	Fit the model to the data produced by the `training_outputs` OutputComputer.

Estimator &	fit_online (ConstMatrixRef training_inputs, const OutputComputer &training_outputs)
	Fit the model to the data produced by the `training_outputs` OutputComputer.

Estimator &	consolidate (ConstMatrixRef training_inputs, ConstMatrixRef training_outputs, const Request request=Request::_)
	Consolidate the model, making sure it is ready for use.

Estimator &	consolidate (ConstMatrixRef training_inputs, ConstMatrixRef training_outputs, Requests requests)
	Consolidate the model, making sure it is ready for use.

virtual double	score (ConstMatrixRef evaluation_inputs, ConstMatrixRef evaluation_outputs) const =0
	Score the estimator assigning a numerical value to its accuracy in predicting the `evaluation_outputs` given the `evaluation_inputs`.

const std::shared_ptr< const Tuner > &	tuner () const
	Get read-only access to the tuner of the estimator.

std::shared_ptr< const Tuner > &	m_tuner ()
	Get read-write access to the tuner of the estimator.

virtual std::unique_ptr< Estimator >	clone () const =0
	Clone the estimator by creating a new instance with the same parameters.

virtual std::string	to_string () const
	Obtain the string representation of this object.

Public Member Functions inherited from lucid::Parametrizable
template<IsAnyOf< int, double, const Vector & > T>
T	get (Parameter parameter) const
	Get the value of the specified `parameter`.

template<Parameter P>
internal::ParameterType< P >::ref_type	get () const
	Get the value of the specified `parameter`.

std::variant< int, double, Vector >	get (Parameter parameter) const
	Get the value of the specified `parameter`.

void	set (Parameter parameter, const std::variant< int, double, Vector > &value)
	Set the `parameter` to the indicated `value`.

template<Parameter P>
void	set (const std::variant< int, double, Vector > &value)
	Set the `parameter` to the indicated `value`.

void	set (Parameter parameter, std::size_t idx, const std::variant< std::vector< int >, std::vector< double >, std::vector< Vector > > &values)
	Set the `parameter` to the `index`-th value among the indicated `values`.

template<Parameter P>
void	set (std::size_t idx, const std::variant< std::vector< int >, std::vector< double >, std::vector< Vector > > &values)
	Set the `parameter` to the `index`-th value among the indicated `values`.

virtual void	set (Parameter parameter, int value)
	Set the `parameter` to the indicated `value`.

virtual void	set (Parameter parameter, double value)
	Set the `parameter` to the indicated `value`.

virtual void	set (Parameter parameter, const Vector &value)
	Set the `parameter` to the indicated `value`.

template<Parameter P>
void	set (typename internal::ParameterType< P >::ref_type value)
	Set the `parameter` to the indicated `value`.

bool	has (const Parameter parameter) const
	Check whether the `parameter` is present in this object.

Parameters	parameters () const
	Get read-only access to the parameters of the parametrizable object.

std::vector< Parameter >	parameters_list () const
	Get read-only access to the list of parameters of the parametrizable object.

Parametrizable &	load (const Parametrizable &o)
	Load parameters from another `Parametrizable` object.

Protected Member Functions
virtual Estimator &	consolidate_impl (ConstMatrixRef training_inputs, ConstMatrixRef training_outputs, Requests requests)=0
	Concrete implementation of the consolidate method.

Protected Member Functions inherited from lucid::Parametrizable
virtual int	get_i (Parameter parameter) const
	Get the value of the specified `parameter`.

virtual double	get_d (Parameter parameter) const
	Get the value of the specified `parameter`.

virtual const Vector &	get_v (Parameter parameter) const
	Get the value of the specified `parameter`.

Private Attributes
std::shared_ptr< const Tuner >	tuner_
	Tuner used during fitting if no other turner is provided. If null, no tuning is performed.

Additional Inherited Members
Protected Attributes inherited from lucid::Parametrizable
Parameters	parameters_
	Parameters supported by this object.

Detailed Description

Given two vector spaces, \( \texttip{\mathcal{X}}{Polish sample vector space} \subseteq \mathbb{R}^{d_x} \) and \( \texttip{\mathcal{Y}}{Polish sample vector space} \subseteq \mathbb{R}^{d_y} \), and a map \( f: \mathcal{X} \to \mathcal{Y} \), the Estimator's goal is to produce a model \( f^*:\mathcal{X} \to \mathcal{Y} \) that best approximates \( f \).

Constructor & Destructor Documentation

◆ Estimator()

lucid::Estimator::Estimator	(	Parameters	parameters = NoParameters,
		const std::shared_ptr< const Tuner > &	tuner = nullptr )

explicit

Construct a new Estimator object.

If no tuner is provided, the estimator will not use any during the fitting process, keeping the hyperparameters it was initialised with.

Parameters

parameters	parameters of the estimator, default to no specific parameter
tuner	Tuner object used to find the best hyperparameters for the model. If none has been provided, the estimator will not use any tuner during the fitting process, keeping the hyperparameters it was initialised with.

Member Function Documentation

◆ clone()

virtual std::unique_ptr< Estimator > lucid::Estimator::clone ( ) const

nodiscardpure virtual

Clone the estimator by creating a new instance with the same parameters.

Returns: new instance of the estimator

Implemented in lucid::KernelRidgeRegressor, and lucid::ModelEstimator.

◆ consolidate() [1/2]

Estimator & lucid::Estimator::consolidate	(	ConstMatrixRef	training_inputs,
		ConstMatrixRef	training_outputs,
		const Request	request = Request::_ )

inline

Consolidate the model, making sure it is ready for use.

No fitting process is performed, and the hyperparameters are not updated, but the estimator may change its internal state so it can be used for predictions. After the process is completed, the estimator can be used to make predictions on new data. The request parameter is used to specify an additional option for the consolidation process, like whether to compute some additional values used by some tuners.

Note: This is a low-level method that allows the user great control over the behaviour of the estimator. It is usually recommended to use fit with the desired tuner instead.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data. The number of rows should be equal to the number of training outputs
training_outputs	training output data. The number of rows should be equal to the number of training inputs
request	request for the consolidation process. Defaults to no specific request being made

Returns: reference to the estimator

◆ consolidate() [2/2]

Estimator & lucid::Estimator::consolidate	(	ConstMatrixRef	training_inputs,
		ConstMatrixRef	training_outputs,
		Requests	requests )

Consolidate the model, making sure it is ready for use.

No fitting process is performed, and the hyperparameters are not updated, but the estimator may change its internal state so it can be used for predictions. After the process is completed, the estimator can be used to make predictions on new data. The requests parameter can be used to specify additional options for the consolidation process, like whether to compute some additional values used by some tuners.

Note: This is a low-level method that allows the user great control over the behaviour of the estimator. It is usually recommended to use fit with the desired tuner instead.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data
training_outputs	training output data
requests	requests for the consolidation process

Returns: reference to the estimator

◆ consolidate_impl()

virtual Estimator & lucid::Estimator::consolidate_impl	(	ConstMatrixRef	training_inputs,
		ConstMatrixRef	training_outputs,
		Requests	requests )

protectedpure virtual

Concrete implementation of the consolidate method.

Parameters

training_inputs	training input data
training_outputs	training output data
requests	requests for the consolidation process

Returns: reference to the estimator

Implemented in lucid::KernelRidgeRegressor, and lucid::ModelEstimator.

◆ fit() [1/2]

Estimator & lucid::Estimator::fit	(	ConstMatrixRef	training_inputs,
		ConstMatrixRef	training_outputs )

Fit the model to the given data.

This method will use the object's tuner to find the best hyperparameters for the model. After the process is completed, the estimator can be used to make predictions on new data. If no tuner has been provided during construction, the method is equivalent to consolidate with no specific request.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data
training_outputs	training output data

Returns: reference to this estimator after it has been fitted

◆ fit() [2/2]

Estimator & lucid::Estimator::fit	(	ConstMatrixRef	training_inputs,
		ConstMatrixRef	training_outputs,
		const Tuner &	tuner )

Fit the model to the given data.

This method will use the provided tuner to find the best hyperparameters for the model. After the process is completed, the estimator can be used to make predictions on new data.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data
training_outputs	training output data
tuner	Tuner object used to find the best hyperparameters for the model

Returns: reference to this estimator after it has been fitted

◆ fit_online() [1/2]

Estimator & lucid::Estimator::fit_online	(	ConstMatrixRef	training_inputs,
		const OutputComputer &	training_outputs )

Fit the model to the data produced by the training_outputs OutputComputer.

This method will use the object's tuner to find the best hyperparameters for the model. After the process is completed, the estimator can be used to make predictions on new data. If no tuner has been provided during construction, the method is equivalent to consolidate with no specific request.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data
training_outputs	training output data. It uses an OutputComputer to compute the outputs when needed

Returns: reference to this estimator after it has been fitted

◆ fit_online() [2/2]

Estimator & lucid::Estimator::fit_online	(	ConstMatrixRef	training_inputs,
		const OutputComputer &	training_outputs,
		const Tuner &	tuner )

Fit the model to the data produced by the training_outputs OutputComputer.

This method will use the provided tuner to find the best hyperparameters for the model. After the process is completed, the estimator can be used to make predictions on new data.

Precondition: The number of rows in the training inputs should be equal to the number of rows in the training outputs.

Parameters

training_inputs	training input data
training_outputs	training output data. It uses an OutputComputer to compute the outputs when needed
tuner	Tuner object used to find the best hyperparameters for the model

Returns: reference to this estimator after it has been fitted

◆ m_tuner()

std::shared_ptr< const Tuner > & lucid::Estimator::m_tuner ( )

inline

Get read-write access to the tuner of the estimator.

Can be null

Returns: tuner of the estimator

◆ operator()()

Matrix lucid::Estimator::operator() ( ConstMatrixRef x ) const

nodiscard

A model is a function that takes a \( n \times d_x \) matrix of row vectors in the input space \( \mathcal{X} \) and returns a \( n \times d_y \) matrix of row vectors in the output space \( \mathcal{Y} \).

Precondition: The estimator should be fitted before calling this method.

Parameters

x	\( n \times d_x \) matrix of row vectors in \( \mathcal{X} \)

Returns: \( n \times d_y \) matrix of row vectors in \( \mathcal{Y} \)

◆ predict()

virtual Matrix lucid::Estimator::predict ( ConstMatrixRef x ) const

nodiscardpure virtual

A model is a function that takes a \( n \times d_x \) matrix of row vectors in the input space \( \mathcal{X} \) and returns a \( n \times d_y \) matrix of row vectors in the output space \( \mathcal{Y} \).

Precondition: The estimator should be fitted before calling this method.

Parameters

x	\( n \times d_x \) matrix of row vectors in \( \mathcal{X} \)

Returns: \( n \times d_y \) matrix of row vectors in \( \mathcal{Y} \)

Implemented in lucid::KernelRidgeRegressor, and lucid::ModelEstimator.

◆ score()

virtual double lucid::Estimator::score	(	ConstMatrixRef	evaluation_inputs,
		ConstMatrixRef	evaluation_outputs ) const

nodiscardpure virtual

Score the estimator assigning a numerical value to its accuracy in predicting the evaluation_outputs given the evaluation_inputs.

Given the evaluation inputs \( x = \{ x_1, \dots, x_n \} \), where \( x_i \in \mathcal{X} \subseteq \mathbb{R}^{d_x}, 0 \le i \le n \), we want to give a numerical score to the model's predictions \( \hat{y} = \{ \hat{y}_1, \dots, \hat{y}_n \} \) with respect to the true outputs \( y = \{ y_1, \dots, y_n \} \), where \( y_i \in \mathcal{Y} \subseteq \mathbb{R}^{d_y}, 0 \le i \le n \).

Note: By default, the score is computed using the scorer::r2_score.

Precondition: The methods fit or consolidate should have been called at least once before calling this method.

Parameters

evaluation_inputs	\( \texttip{n}{Number of samples} \times \texttip{d_x}{Dimension of the input vector space} \) evaluation input data
evaluation_outputs	\( \texttip{n}{Number of samples} \times \texttip{d_y}{Dimension of the output vector space} \) evaluation output data

Returns: score of the model

Implemented in lucid::KernelRidgeRegressor, and lucid::ModelEstimator.

◆ to_string()

std::string lucid::Estimator::to_string ( ) const

nodiscardvirtual

Obtain the string representation of this object.

Returns: string representation of this object

Reimplemented in lucid::KernelRidgeRegressor, and lucid::ModelEstimator.

◆ tuner()

const std::shared_ptr< const Tuner > & lucid::Estimator::tuner ( ) const

inlinenodiscard

Get read-only access to the tuner of the estimator.

Can be null

Returns: tuner of the estimator

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

lucid/model/Estimator.h
lucid/model/Estimator.cpp

Public Member Functions

Protected Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Estimator()

Member Function Documentation

◆ clone()

◆ consolidate() [1/2]

◆ consolidate() [2/2]

◆ consolidate_impl()

◆ fit() [1/2]

◆ fit() [2/2]

◆ fit_online() [1/2]

◆ fit_online() [2/2]

◆ m_tuner()

◆ operator()()

◆ predict()

◆ score()

◆ to_string()

◆ tuner()