mlr3learners_lightgbm_multiclass.Rmd

---
title: "mlr3learners.lightgbm: Multiclass Classification Example"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    keep_md: true
vignette: >
  %\VignetteIndexEntry{mlr3learners_lightgbm_multiclass}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(mlr3)
library(mlr3learners.lightgbm)
```

# Create the mlr3 task

```{r}
task = mlr3::tsk("iris")
```

To have independent validation data and test data, we further create a list `split`, containing the respective row indices.

```{r}
set.seed(17)
split = list(
  train_index = sample(seq_len(task$nrow), size = 0.7 * task$nrow)
)
split$test_index = setdiff(seq_len(task$nrow), split$train_index)
                            
table(task$data()[split$train_index, task$target_names, with = F])
table(task$data()[split$test_index, task$target_names, with = F])
```

# Instantiate the lightgbm learner 

Then, the `classif.lightgbm` class needs to be instantiated: 

```{r}
learner = mlr3::lrn("classif.lightgbm", objective = "multiclass")
```

# Configure the learner 

In the next step, some of the learner's parameters need to be set. E.g., the parameters `num_iterations` and `early_stopping_round` can be set here. Please refer to the [LightGBM manual](https://lightgbm.readthedocs.io) for further details these parameters. Almost all possible parameters have been implemented here. You can inspect them using the following command: 

```{r eval=FALSE}
learner$param_set
```

```{r}
learner$param_set$values = mlr3misc::insert_named(
  learner$param_set$values,
    list(
    "early_stopping_round" = 10,
    "learning_rate" = 0.1,
    "seed" = 17L,
    "metric" = "multi_logloss",
    "num_iterations" = 100,
    "num_class" = 3
  )
)
```

# Train the learner 

The learner is now ready to be trained by using its `train` function. 

```{r results='hide', message=FALSE, warning=FALSE, error=FALSE}
learner$train(task, row_ids = split$train_index)
```

# Evaluate the model performance 

Basic metrics can be assessed directly from the learner model: 

```{r}
learner$model$current_iter()
```

The learner's `predict` function returns an object of mlr3's class `PredictionClassif`. 

```{r}
predictions = learner$predict(task, row_ids = split$test_index)
head(predictions$response)
```

The predictions object includes also a confusion matrix:

```{r}
predictions$confusion
```

Further metrics can be calculated by using mlr3 measures:

```{r}
predictions$score(mlr3::msr("classif.logloss"))
```

The variable importance plot can be calculated by using the learner's `importance` function:

```{r}
importance = learner$importance()
importance
```