---
title: "Introduction to `rbooster`"
author: "Fatih Sağlam"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{booster}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction
This package aims to enable the use of classifiers in boosting family algorithms, apart from decision trees and other classical weak classifiers. The current scope of the package includes Real AdaBoost and Discrete AdaBoost, as well as multiclass versions of these methods, the SAMME and SAMME.R algorithms.

## Future plans
I am aware that there have been attempts to create frameworks that allow using custom functions in boosting (e.g. boostr). However, they are too complex to my taste. I haven't seen a simple-to-use package that handles  different boosting methods. What can be done simply in Python, why can't it be done in R? That is my point. The package is still in the starting phase (a baby package). Things on my mind:

* I will add more boosting algorithms such as GentleBoost, LogitBoost, Gradient Boosting and XGBoost. 
* I will enable the establishment of not only classification but also regression models with these methods. 
* In accordance with the main purpose of the package, I will allow the use of regression models prepared by the user in boosting algorithms. 
* Custom resampling methods to use in each boosting step for class imbalanced datasets and some pre-ready methods such as random-undersampling, random-oversampling and SMOTE.
* Data pre-processing methods (e.g. PCA, KPCA, discretization, dummyfication).
* Missing data handling methods (e.g. list-wise deletion, row-wise deletion, data imputation)
* If I can, I will add a generalizable feature importance function for all weak classifier (or regression) methods. I'm not sure it can be done. I will work on this issue. I am open to any advice on this matter. 
* I will prepare a shiny app inside the package, which you can upload your own data and use any functions available. Varying visualizations and performance metrics will be available. And you will be able to add your custom function using the app. 
* I can add the bagging algorithms after all the plans are complete. But I can't say I'm very keen on this, since it is just model averaging with bootstrapped models. I am not a fan of bagging.

# `booster` function
There is a function for each method in the package. But the main function is the `booster`. By using this function it will be possible to access everything. Let me give you information about the features of this function and how to use it. First of all, 2 different AdaBoost methods can be applied with the `booster` function: Real AdaBoost and Discrete AdaBoost. Let us use glass0 dataset in `imbalance` package and prepare a train and test dataset. test dataset is not mandatory. 

```{r}
library(rbooster)
cv_sampler <- function(y, train_proportion) {
  unlist(lapply(unique(y), function(m) sample(which(y==m), round(sum(y==m))*train_proportion)))
}

library(imbalance)
data <- glass0
p <- ncol(data) - 1

x <- data[,1:p]
y <- data[, p + 1]

train_i <- cv_sampler(y, 0.9)
x_train <- x[train_i,]
y_train <- y[train_i]

x_test <- x[-train_i,]
y_test <- y[-train_i]
```

This is a two-class dataset. Let us use decision tree to build Discrete and Real AdaBoost models.

```{r, fig.width=7, fig.height=6, fig.align='center'}
m_discrete <- booster(x_train = x_train, 
        y_train = y_train, 
        classifier = "rpart", 
        method = "discrete",
        x_test = x_test,
        y_test = y_test, 
        weighted_bootstrap = FALSE,
        max_iter = 20, 
        lambda = 1, 
        print_detail = TRUE, 
        print_plot = TRUE, 
        bag_frac = 0.8, 
        p_weak = 4)

m_real <- booster(x_train = x_train, 
                      y_train = y_train, 
                      classifier = "rpart", 
                      method = "real",
                      x_test = x_test,
                      y_test = y_test, 
                      weighted_bootstrap = FALSE,
                      max_iter = 20, 
                      lambda = 1, 
                      print_detail = TRUE, 
                      print_plot = TRUE, 
                      bag_frac = 0.8, 
                      p_weak = 4)
```

We can obtain predictions on `x_test` like:

```{r}
head(m_discrete$test_prediction)
head(m_real$test_prediction)

table(y_test, m_discrete$test_prediction)
table(y_test, m_real$test_prediction)
```

However `x_test` is used to validate on `y_test`. So without `y_test`, `x_test` is ignored. `x_test` and `y_test` can be set to `NULL`, they are not mandatory for model to be established. You can use the usual `predict` function.

```{r}
pred_discrete <- predict(object = m_discrete, newdata = x_test, type = "pred")
pred_real <- predict(object = m_real, newdata = x_test, type = "pred")

all(pred_discrete == m_discrete$test_prediction)
all(pred_discrete == m_discrete$test_prediction)
```

In `predict` function `type` can be "pred" or "prob". "prob" will gives class probability matrix.

```{r}
prob_discrete <- predict(object = m_discrete, newdata = x_test, type = "prob")
head(prob_discrete)
```

Let us use Glass dataset in mlbench for multiclass classification example.
```{r, fig.width=7, fig.height=6, fig.align='center'}

library(mlbench)
data(Glass)
data <- Glass
p <- ncol(data) - 1

x <- data[,1:p]
y <- data[, p + 1]

train_i <- cv_sampler(y, 0.9)
x_train <- x[train_i,]
y_train <- y[train_i]

x_test <- x[-train_i,]
y_test <- y[-train_i]


par(mfrow = c(2,1))
m_discrete <- booster(x_train = x_train, 
                      y_train = y_train, 
                      classifier = "rpart", 
                      method = "discrete",
                      x_test = x_test,
                      y_test = y_test, 
                      weighted_bootstrap = FALSE,
                      max_iter = 20, 
                      lambda = 1, 
                      print_detail = FALSE, 
                      print_plot = TRUE, 
                      bag_frac = 0.8, 
                      p_weak = p)

m_real <- booster(x_train = x_train, 
                  y_train = y_train, 
                  classifier = "rpart", 
                  method = "real",
                  x_test = x_test,
                  y_test = y_test, 
                  weighted_bootstrap = FALSE,
                  max_iter = 20, 
                  lambda = 0.1, 
                  print_detail = FALSE, 
                  print_plot = TRUE, 
                  bag_frac = 1, 
                  p_weak = p)

invisible(dev.off())
pred_discrete <- predict(object = m_discrete, newdata = x_test, type = "pred")
pred_real <- predict(object = m_real, newdata = x_test, type = "pred")

table(y_test, pred_discrete)
table(y_test, pred_real)
```

There is a major reason people use decision trees in boosting. It fits very quick. Let us try a pre-ready classifier Discrete Naive Bayes, "dnb", in `rbooster`.

```{r, fig.width=7, fig.height=6, fig.align='center'}
par(mfrow = c(2,1))
m_discrete <- booster(x_train = x_train, 
                      y_train = y_train, 
                      classifier = "dnb", 
                      method = "discrete",
                      x_test = x_test,
                      y_test = y_test, 
                      weighted_bootstrap = FALSE,
                      max_iter = 250, 
                      lambda = 1, 
                      print_detail = FALSE, 
                      print_plot = TRUE, 
                      bag_frac = 0.5, 
                      p_weak = 4)

m_real <- booster(x_train = x_train, 
                  y_train = y_train, 
                  classifier = "dnb", 
                  method = "real",
                  x_test = x_test,
                  y_test = y_test, 
                  weighted_bootstrap = FALSE,
                  max_iter = 250, 
                  lambda = 1e-4, 
                  print_detail = FALSE, 
                  print_plot = TRUE, 
                  bag_frac = 0.2, 
                  p_weak = 4)

invisible(dev.off())
pred_discrete <- predict(object = m_discrete, newdata = x_test, type = "pred")
pred_real <- predict(object = m_real, newdata = x_test, type = "pred")

table(y_test, pred_discrete)
table(y_test, pred_real)
```
I needed to play with lambda, bag_frac and p_weak a lot to find a good setting so that "dnb" fits. It is still not quite successful. Methods other that decision trees require care. 

## Custom Classifier
Classifier function requires x_train, y_train, weights as mandatory. Output of Classifier function will be the input for Predictor function. Predictor function requires model, which is the output of Classifier, x_new, which is the train features, and type inputs. type can only be "pred" or "prob". "pred" must give a class vector of predictions, and "prob" must give a matrix of class probabilities. "pred" is mandatory for both Real and Discrete AdaBoost. However, Discrete AdaBoost does not require type "prob". Let me prepare a made up Classifier function. 

```{r}

classifier_lm <- function(x_train, y_train, weights, ...){
  y_train_code <- c(-1,1)
  y_train_coded <- sapply(levels(y_train), function(m) y_train_code[(y_train == m) + 1])
  y_train_coded <- y_train_coded[,1]
  if (is.null(weights)) {
    weights <- rep(1, length(y_train))
  }
  
  model <- lm.wfit(x = as.matrix(cbind(1,x_train)), y = y_train_coded, w = weights)
  return(list(coefficients = model$coefficients,
              levels = levels(y_train)))
}

predictor_lm <- function(model, x_new, type = "pred", ...) {
  coef <- model$coefficients
  levels <- model$levels
  
  fit <- as.matrix(cbind(1, x_new))%*%coef
  probs <- 1/(1 + exp(-fit))
  probs <- data.frame(probs, 1 - probs)
  colnames(probs) <- levels
  
  if (type == "pred") {
    preds <- factor(levels[apply(probs, 1, which.max)], levels = levels, labels = levels)
    return(preds)
  }
  if (type == "prob") {
    return(probs)
  }
}
```

This classifier will convert y_train into (-1,1) codes and predictions will be transformed into the range (0,1) using logit transformation. These values will be used as probabilities and class with the higher probabilitiy will be selected as prediction. Since this is a linear classification method, it should work well with boosting. Let us see.

```{r, fig.width=7, fig.height=6, fig.align='center'}
data <- glass0
p <- ncol(data) - 1

x <- data[,1:p]
y <- data[, p + 1]

train_i <- cv_sampler(y, 0.9)
x_train <- x[train_i,]
y_train <- y[train_i]

x_test <- x[-train_i,]
y_test <- y[-train_i]

par(mfrow = c(2,1))
m_discrete <- booster(x_train = x_train, 
                      y_train = y_train, 
                      classifier = classifier_lm,
                      predictor = predictor_lm,
                      method = "discrete",
                      x_test = x_test,
                      y_test = y_test, 
                      weighted_bootstrap = FALSE,
                      max_iter = 600, 
                      lambda = 2, 
                      print_detail = FALSE, 
                      print_plot = TRUE, 
                      bag_frac = 0.4, 
                      p_weak = 4)

m_real <- booster(x_train = x_train, 
                  y_train = y_train, 
                  classifier = classifier_lm,
                  predictor = predictor_lm,
                  method = "real",
                  x_test = x_test,
                  y_test = y_test, 
                  weighted_bootstrap = FALSE,
                  max_iter = 200, 
                  lambda = 0.1, 
                  print_detail = FALSE, 
                  print_plot = TRUE, 
                  bag_frac = 1, 
                  p_weak = 4)

invisible(dev.off())
pred_discrete <- predict(object = m_discrete, newdata = x_test, type = "pred")
pred_real <- predict(object = m_real, newdata = x_test, type = "pred")

table(y_test, pred_discrete)
table(y_test, pred_real)
```
It fits but not quite there. `print_plot` can be set to `FALSE`. In that case, the same plot can be generated using `plot` function.

```{r, fig.width=7, fig.height=6, fig.align='center'}
par(mfrow = c(2,1))
plot(m_discrete)
plot(m_real)
invisible(dev.off())
```

Pre-ready weak classifiers are "rpart", "gnb", "dnb", "earth" and "glm" which are CART, Gaussian Naive Bayes, Discrete Naive Bayes, Multivariate Adaptive Regression Splines from earth package and logistic regression respectively. "glm" is not capable of multiclass classification. booster object can be used with prediction, plot, and print functions. For other details about booster object and its outputs, please see help document.