Skip to contents

Create a New Learner

create_learner.Rd

Helper function to generate all required files, and fill in fields, for new learners.

Usage

create_learner(
  pkg = ".",
  classname,
  algorithm,
  type,
  key = tolower(classname),
  package = tolower(classname),
  caller,
  feature_types,
  predict_types,
  properties = NULL,
  references = FALSE,
  gh_name
)

Arguments

pkg

character(1)
Path to the mlr3extralearners package.

classname

character(1)
Suffix for R6 class name passed to LearnerTypeclassname.

algorithm

character(1)
Brief description of algorithm for documentation title.

type

character(1)
See mlr3::mlr_reflections$task_types$type.

key

character(1)
id for learner, if not provided defaults to the classname in all lower case.

package

character(1)
Package from which the learner is implemented, defaults to the classname in all lower case.

caller

character(1)
Training function called from the implemented package.

feature_types

character()
Feature types that can be handled by the learner, see mlr3::mlr_reflections$task_feature_types.

predict_types

character()
Prediction types that can be made by the learner, see mlr3::mlr_reflections$learner_predict_types.

properties

character()
Properties that can be handled by the learner, see mlr3::mlr_reflections$learner_properties.

references

logical(1)
Set to TRUE if you want to add references for the learner.

gh_name

character(1)
Your GitHub handle, used to add you as the maintainer of the learner.

Details

This function does the following:

  1. Creates a learner_package_type_key.R file for the implemented learner.

  2. Creates a test_package_type_key.R file for unit testing the learner.

  3. Creates a test_paramtest_package_type_key.R file for testing correct implementation of learner parameters.

  4. Creates a test_package.yml file for running unit tests in GitHub actions

  5. Automatically completes the test (2), and yaml files (4)

  6. Automatically adds the learner package to the DESCRIPTION file

  7. For the learner file all fields are automatically filled but methods must be manually added along with the parameter set, this is clearly marked up in the files.

To create a learner you must follow these steps:

  1. Run this function with as many arguments as possible

  2. Manually add .train, .predict private methods for the learner, as well as adding the param_set and possibly param_vals. If properties include "oob_error" and/or "importance" then add these public methods manually.

  3. Check the paramtests and unit tests pass locally.

  4. Run

    1. devtools::document(roclets = c('rd', 'collate', 'namespace'))

    2. styler::style_pkg(style = styler::mlr_style) (you may need to first run remotes::)

    3. usethis::use_tidy_description()

    4. lintr::lint_package()

  5. Open a pull request to https://github.com/mlr-org/mlr3extralearners/pulls with the new learner template.

Examples

if (FALSE) {
# Simpler linear regression example
create_learner(
  classname = "LM",
  algorithm = "linear regression",
  type = "regr",
  package = "stats",
  caller = "lm",
  feature_types = c("logical", "integer", "numeric", "factor"),
  predict_types = c("response", "se"),
  properties = "weights",
  gh_name = "RaphaelS1"
)

# Slightly more complex random forest learner
create_learner(
  classname = "RandomForestSRC",
  algorithm = "random forest",
  type = "surv",
  package = "randomForestSRC",
  caller = "rfsrc",
  feature_types = c("logical", "integer", "numeric", "factor"),
  predict_types = c("crank", "distr"),
  properties = c("importance", "missings", "oob_error", "weights"),
  references = TRUE,
  gh_name = "RaphaelS1"
)
}