---
title: "Migrating from MFF 0.2.x"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Migrating from MFF 0.2.x}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Version 1.0.0 replaces the 0.2.x interface. The functions `mff()`,
`tune.mff()`, `model.train()` and `boot.train()`, and the `mff` class with
its methods, have been removed. Scripts written for 0.2.x must be updated
using the mappings below; numerical results can differ because the new
interface honors `nstart` for every clustering method.

## Functions

| MFF 0.2.x | MFF 1.0.0 |
|---|---|
| prediction matrices passed directly | `mff_pool()` creates an `mff_prediction_pool` |
| `mff(x, y, c = 2)` | `fit_mff(pool, clusters = 2)` |
| `tune.mff(x, y, max_c = 4)` | `tune_mff(pool, clusters = 2:4)` |
| `model.train(target, data, ntest, nvalid)` | `model_train(formula, data, split = mff_split(...), learners = ...)` |
| `boot.train(target, data, ntest, nvalid, B)` | `boot_train(formula, data, split = mff_split(...), times = B)` |
| `predict(fit, pred_matrix)$mff_preds` | `predict(fit, newdata)` |
| `evaluate()` | `evaluate()` (unchanged formulas) |

## Arguments

| MFF 0.2.x | MFF 1.0.0 |
|---|---|
| `c`, `max_c` | `clusters` (a value for `fit_mff()`, a vector for `tune_mff()`) |
| `m_seq`, `eta_seq` | `m`, `eta` |
| `mff.method`, `method` | `method` |
| `eval.method` | `metric` |
| `iter.max` | `iter_max` |
| `stand` | `standardize` |
| `clustering.reduction` | `reduction` |
| `seed`, `parallel`, `num_cores`, `logging` | `control = mff_control(seed, parallel, workers, verbose)` |
| `ntest`, `nvalid` (random split) | `split = mff_split(train, validation, test)` (explicit rows) |

## Results

| 0.2.x list component | 1.0.0 accessor |
|---|---|
| `pred_matrix_valid`, `pred_matrix_test` | `validation_predictions(pool)`, `test_predictions(pool)` |
| `y_valid`, `y_test` | `validation_observed(pool)`, `test_observed(pool)` |
| `best_params` | `selected_configuration(fit)` |
| `best_cluster` | `selected_function(fit)` |
| `best_weight` | `weights(fit)` |
| `weights` | `weights(fit, type = "all")` |
| `cluster_scores`, `best_scores` | `validation_scores(fit)` |
| `search_diagnostics` | `search_results(fit)` |

## A translated workflow

A 0.2.x bootstrap workflow, `boot.train("Volume", trees, ntest = 8,
nvalid = 8, B = 6)` followed by `tune.mff()`, becomes:

```{r}
split <- mff_split(train = 1:15, validation = 16:23, test = 24:31)
pool <- boot_train(Volume ~ Girth + Height, datasets::trees, split,
                   times = 6, control = mff_control(seed = 8))
fit <- tune_mff(pool, clusters = 2:3, method = "kmeans")
evaluate(predict(fit, pool), test_observed(pool))
```
