mlr-org/mlr3learners.template

Learner from package {<package>} for mlr3

mlr3learners.template

This packages provides a template for adding new learners for mlr3.

Creating new learners is covered in detail in section "Adding new learners" in the mlr3book. This package serves as a starting point for learners to share with others.

Instructions

This repository is a template repository to create a learner that aligns with existing mlr3 learners. Perform the following tasks to create your learner:

1. Replace all instances of
   1. <package> with the name of the underlying package.
   2. <type> with the learner type, e.g. Classif or Regr.
   3. <algorithm> with the name of the algorithm, e.g randomForest.
2. Rename files following the same scheme as in 1).
3. Check if the learner supports feature importance internally. If yes, add a importance() method in the respective learner class.
4. Check if the learner supports out-of-bag error estimation internally. If yes, add a oob_error() method in the respective learner class.
5. Add yourself as the maintainer in DESCRIPTION.
6. Set up Continuous Integration (CI). The GitHub Actions YAML files live in .github/workflows.
   1. Replace <package> in l.17 of tic.R with the name of the package.
   2. Update the "Paramtest" files in inst/paramtest/ to ensure no parameter was forgotten in the learner. Make sure that the CI test passes for "Param Check".
   3. Update the badge in README.md with the package name.
7. Run devtools::document(roclets = c('rd', 'collate', 'namespace')) to create the NAMESPACE and man/ files.
8. Leave the files in man-roxygen as they are - they will just work.
9. Run usethis::use_tidy_description() to format DESCRIPTION.
10. Test your learner locally by running devtools::test()
11. Check your package by running rcmdcheck::rcmdcheck()
12. Check if your learner complies with the mlr style guide.
13. Ensure that the CI builds complete successfully (via the "Actions" menu in the repo).
14. Check on last small details like the name of the learner package and for possible leftovers of the placeholders used in the template.

Last but not least go through

👉 this checklist 📄

to make sure your learner is ready for review.

After your learner is accepted, it can be added to mlr3learners.drat, making it installabe via the canonical install.packages() function without the need to live on CRAN.

Resources for adding a new learner (summary)

• mlr3learners.template
• mlr3book section "Adding new learners" including FAQ
• Checklist prior to requesting a review

!Important!: Delete all instructions up to this point and just leave the part below.

mlr3learners.<package>

Adds <algorithm1> and <algorithm2> from the {} package to {mlr3}.

Install the latest release of the package via

install.packages("mlr3learners.<package>")

by following the instructions in the mlr3learners.drat README.

Alternatively, you can install the latest version of {mlr3learners.} from Github with:

remotes::install_github("mlr3learners/mlr3learners.<package>")

mlr3learners.template's Issues

Checklist for Learner Submission

• Run styler::style_pkg(style = styler::mlr_style) (install pat-s/styler@mlr-style if not yet done)

• Run lintr::lint_package() and fix all issues.

• Run usethis::use_tidy_description() to format the DESCRIPTION file.

• Check that the learner package name is all lower case, e.g. mlr3learners.partykit.

• Ensure that there are not leftover of <package>, <algorithm> or <type> within the learner repo.

• Ensure that the "Parameter Check" passed in the CI (both for the train and predict functions)

• Ensure that "R CMD check" passed in the CI.

• Check that your learners upstream package is not listed in the "Imports" but in the "Suggests" section within the DESCRIPTION file.

• If you changed any parameter defaults: Did you document the change (reason and new default) in the help page of the respective learner?

• Open a Pull Request in the mlr3learners repo to add your learner to the list of "In Progress" learners. Once approved, it will be moved to the "Approved" section.

Rename to mlr3learners.template?

Hello,

You might consider renaming this package to mlr3learners.template - that will just make it closer to what template users will be using for their packages.

Cheers,
Chris

Unable to clone repo

I'm not sure what I need to do differently, but I forked this repo and tried to clone my fork and I get the following error:

$ git clone https://github.com/TylerGrantSmith/mlr3mclust.git
Cloning into 'mlr3mclust'...
remote: Enumerating objects: 36, done.
remote: Counting objects: 100% (36/36), done.
remote: Compressing objects: 100% (32/32), done.
remote: Total 36 (delta 2), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (36/36), done.
error: unable to create file R/Learner<type><function>.R: Invalid argument
error: unable to create file inst/paramtest/test_paramtest_<type>.<algorithm>.R: Invalid argument
error: unable to create file tests/testthat/test_<type>_<name>.R: Invalid argument
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'