---
title: "Multi Class vtreat"
author: "John Mount"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Multi Class vtreat}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
 
[`vtreat`](https://github.com/WinVector/vtreat) can now effectively prepare data for multi-class classification or multinomial modeling.

The two functions needed ([`mkCrossFrameMExperiment()`](https://winvector.github.io/vtreat/reference/mkCrossFrameMExperiment.html) and the `S3` method [`prepare.multinomial_plan()`](https://winvector.github.io/vtreat/reference/prepare.multinomial_plan.html)) are now part of `vtreat`.

Let's work a specific example: trying to model multi-class `y` as a function of `x1` and `x2`.

```{r libs}
library("vtreat")
```

```{r mkex}
# create example data
set.seed(326346)
sym_bonuses <- rnorm(3)
names(sym_bonuses) <- c("a", "b", "c")
sym_bonuses3 <- rnorm(3)
names(sym_bonuses3) <- as.character(seq_len(length(sym_bonuses3)))
n_row <- 1000
d <- data.frame(
  x1 = rnorm(n_row),
  x2 = sample(names(sym_bonuses), n_row, replace = TRUE),
  x3 = sample(names(sym_bonuses3), n_row, replace = TRUE),
  y = "NoInfo",
  stringsAsFactors = FALSE)
d$y[sym_bonuses[d$x2] > 
      pmax(d$x1, sym_bonuses3[d$x3], runif(n_row))] <- "Large1"
d$y[sym_bonuses3[d$x3] > 
      pmax(sym_bonuses[d$x2], d$x1, runif(n_row))] <- "Large2"

knitr::kable(head(d))
```

We define the problem controls and use `mkCrossFrameMExperiment()` to build both a cross-frame and
a treatment plan.

```{r tdef}
# define problem
vars <- c("x1", "x2", "x3")
y_name <- "y"

# build the multi-class cross frame and treatments
cfe_m <- mkCrossFrameMExperiment(d, vars, y_name)
```

The cross-frame is the entity safest for training on (unless you have made separate data split for the 
treatment design step). It uses cross-validation to reduce nested model bias. Some notes on this issue
are available [here](https://winvector.github.io/vtreat/articles/vtreatCrossFrames.html), and [here](https://github.com/WinVector/vtreat/blob/master/extras/vtreat.pdf).

```{r crossframe}
# look at the data we would train models on
str(cfe_m$cross_frame)
```

`prepare()` can apply the designed treatments to new data.  Here we are simulating new 
data by re-using our design data.

```{r treatment_plan}
# pretend original data is new data to be treated
# NA out top row to show processing
for(vi in vars) {
  d[[vi]][[1]] <- NA
}
str(prepare(cfe_m$treat_m, d))
```

Obvious issues include: computing variable importance, and blow up and co-dependency of produced columns.  These we leave for the next modeling step to deal with (this is our philosophy with most issues that involve joint distributions of variables).

We also have per-outcome variable importance.

```{r varimp}
knitr::kable(
  cfe_m$score_frame[, 
                    c("varName", "rsq", "sig", "outcome_level"), 
                    drop = FALSE])
```

One can relate these per-target and per-treatment performances back to original columns by aggregating.

```{r varagg}

tapply(cfe_m$score_frame$rsq, 
       cfe_m$score_frame$origName, 
       max)

tapply(cfe_m$score_frame$sig, 
       cfe_m$score_frame$origName, 
       min)
```