mlexperiments (version 0.0.5)

MLLearnerBase: R6 Class to construct learners

Description

The MLLearnerBase class is used to construct a learner object that can be used with the experiment classes from the mlexperiments package. It is thought to serve as a class to inherit from when creating new learners.

Public fields

cluster_export

A character vector defining the (internal) functions that need to be exported to the parallelization cluster. This is only required when performing a Bayesian hyperparameter optimization. See also parallel::clusterExport().

metric_optimization_higher_better

A logical. Defines the direction of the optimization metric used throughout the hyperparameter optimization. This field is set automatically during the initialization of the MLLearnerBase object. Its purpose is to make it accessible by the evaluation functions from MLTuneParameters.

environment

The environment in which to search for the functions of the learner (default: -1L).

seed

Seed for reproducible results.

Methods

Public methods

• MLLearnerBase$new()

• MLLearnerBase$cross_validation()

• MLLearnerBase$fit()

• MLLearnerBase$predict()

• MLLearnerBase$bayesian_scoring_function()

• MLLearnerBase$clone()

---

Method new()

Create a new MLLearnerBase object.

Usage

MLLearnerBase$new(metric_optimization_higher_better)

Arguments

metric_optimization_higher_better

A logical. Defines the direction of the optimization metric used throughout the hyperparameter optimization.

Returns

A new MLLearnerBase R6 object.

Examples

MLLearnerBase$new(metric_optimization_higher_better = FALSE)

---

Method cross_validation()

Perform a cross-validation with an MLLearnerBase.

Usage

MLLearnerBase$cross_validation(...)

Arguments

...

Arguments to be passed to the learner's cross-validation function.

Details

A wrapper around the private function fun_optim_cv, which needs to be defined when hyperparameters should be optimized with a grid search (required for use with MLTuneParameters, and MLNestedCV. However, the function should be never executed directly but by the respective experiment wrappers MLTuneParameters, and MLNestedCV. For further details please refer to the package's vignette.

Returns

The fitted model.

Examples

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
\dontrun{
# This example cannot be run without further adaptions.
# The method `$cross_validation()` needs to be overwritten when
# inheriting from this class.
learner$cross_validation()
}

---

Method fit()

Fit a MLLearnerBase object.

Usage

MLLearnerBase$fit(...)

Arguments

...

Arguments to be passed to the learner's fitting function.

Details

A wrapper around the private function fun_fit, which needs to be defined for every learner. The return value of this function is the fitted model. However, the function should be never executed directly but by the respective experiment wrappers MLTuneParameters, MLCrossValidation, and MLNestedCV. For further details please refer to the package's vignette.

Returns

The fitted model.

Examples

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
\dontrun{
# This example cannot be run without further adaptions.
# The method `$fit()` needs to be overwritten when
# inheriting from this class.
learner$fit()
}

---

Method predict()

Make predictions from a fitted MLLearnerBase object.

Usage

MLLearnerBase$predict(model, newdata, ncores = -1L, ...)

Arguments

model

A fitted model of the learner (as returned by MLLearnerBase$fit()).

newdata

The new data for which predictions should be made using the model.

ncores

An integer to specify the number of cores used for parallelization (default: -1L).

...

Further arguments to be passed to the learner's predict function.

Details

A wrapper around the private function fun_predict, which needs to be defined for every learner. The function must accept the three arguments model, newdata, and ncores and is a wrapper around the respective learner's predict-function. In order to allow the passing of further arguments, the ellipsis (...) can be used. The function should return the prediction results. However, the function should be never executed directly but by the respective experiment wrappers MLTuneParameters, MLCrossValidation, and MLNestedCV. For further details please refer to the package's vignette.

Returns

The predictions for newdata.

Examples

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
\dontrun{
# This example cannot be run without further adaptions.
# The method `$predict()` needs to be overwritten when
# inheriting from this class.
learner$fit()
learner$predict()
}

---

Method bayesian_scoring_function()

Perform a Bayesian hyperparameter optimization with an MLLearnerBase.

Usage

MLLearnerBase$bayesian_scoring_function(...)

Arguments

...

Arguments to be passed to the learner's Bayesian scoring function.

Details

A wrapper around the private function fun_bayesian_scoring_function, which needs to be defined when hyperparameters should be optimized with a Bayesian process (required for use with MLTuneParameters, and MLNestedCV. However, the function should be never executed directly but by the respective experiment wrappers MLTuneParameters, and MLNestedCV. For further details please refer to the package's vignette.

Returns

The results of the Bayesian scoring.

Examples

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
\dontrun{
# This example cannot be run without further adaptions.
# The method `$bayesian_scoring_function()` needs to be overwritten when
# inheriting from this class.
learner$bayesian_scoring_function()
}

---

Method clone()

The objects of this class are cloneable with this method.

Usage

MLLearnerBase$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Details

The learner class exposes 4 methods that can be defined:

• $fit A wrapper around the private function fun_fit, which needs to be defined for every learner. The return value of this function is the fitted model.

• $predict A wrapper around the private function fun_predict, which needs to be defined for every learner. The function must accept the three arguments model, newdata, and ncores and is a wrapper around the respective learner's predict-function. In order to allow the passing of further arguments, the ellipsis (...) can be used. The function should return the prediction results.

• $cross_validation A wrapper around the private function fun_optim_cv, which needs to be defined when hyperparameters should be optimized with a grid search (required for use with MLTuneParameters, and MLNestedCV).

• $bayesian_scoring_function A wrapper around the private function fun_bayesian_scoring_function, which needs to be defined when hyperparameters should be optimized with a Bayesian process (required for use with MLTuneParameters, and MLNestedCV).

For further details please refer to the package's vignette.

See Also

MLTuneParameters, MLCrossValidation, and MLNestedCV

MLTuneParameters, MLCrossValidation, and MLNestedCV

MLTuneParameters, MLCrossValidation, and MLNestedCV

ParBayesianOptimization::bayesOpt(), MLTuneParameters, and MLNestedCV

Examples

MLLearnerBase$new(metric_optimization_higher_better = FALSE)


## ------------------------------------------------
## Method `MLLearnerBase$new`
## ------------------------------------------------

MLLearnerBase$new(metric_optimization_higher_better = FALSE)


## ------------------------------------------------
## Method `MLLearnerBase$cross_validation`
## ------------------------------------------------

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
if (FALSE) {
# This example cannot be run without further adaptions.
# The method `$cross_validation()` needs to be overwritten when
# inheriting from this class.
learner$cross_validation()
}


## ------------------------------------------------
## Method `MLLearnerBase$fit`
## ------------------------------------------------

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
if (FALSE) {
# This example cannot be run without further adaptions.
# The method `$fit()` needs to be overwritten when
# inheriting from this class.
learner$fit()
}


## ------------------------------------------------
## Method `MLLearnerBase$predict`
## ------------------------------------------------

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
if (FALSE) {
# This example cannot be run without further adaptions.
# The method `$predict()` needs to be overwritten when
# inheriting from this class.
learner$fit()
learner$predict()
}


## ------------------------------------------------
## Method `MLLearnerBase$bayesian_scoring_function`
## ------------------------------------------------

learner <- MLLearnerBase$new(metric_optimization_higher_better = FALSE)
if (FALSE) {
# This example cannot be run without further adaptions.
# The method `$bayesian_scoring_function()` needs to be overwritten when
# inheriting from this class.
learner$bayesian_scoring_function()
}