---
title: "A-quick-tour-of-tMoE"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{A-quick-tour-of-tMoE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
library(knitr)
knitr::opts_chunk$set(
	fig.align = "center",
	fig.height = 5.5,
	fig.width = 6,
	warning = FALSE,
	collapse = TRUE,
	dev.args = list(pointsize = 10),
	out.width = "90%",
	par = TRUE
)
knit_hooks$set(par = function(before, options, envir)
  { if (before && options$fig.show != "none") 
       par(family = "sans", mar = c(4.1,4.1,1.1,1.1), mgp = c(3,1,0), tcl = -0.5)
})
```

```{r, message = FALSE, echo = FALSE}
library(meteorits)
```

# Introduction

**TMoE** (t Mixture-of-Experts) provides a flexible and robust modelling 
framework for heterogenous data with possibly heavy-tailed distributions and 
corrupted by atypical observations. **TMoE** consists of a mixture of *K* t 
expert regressors network (of degree *p*) gated by a softmax gating network (of
degree *q*) and is represented by:

* The gating network parameters `alpha`'s of the softmax net.
* The experts network parameters: The location parameters (regression 
coefficients) `beta`'s, scale parameters `sigma`'s, and the degree of freedom 
(robustness) parameters `nu`'s. **TMoE** thus generalises mixtures of (normal, 
t, and) distributions and mixtures of regressions with these distributions. For
example, when $q=0$, we retrieve mixtures of (t-, or normal) regressions, and 
when both $p=0$ and $q=0$, it is a mixture of (t-, or normal) distributions. 
It also reduces to the standard (normal, t) distribution when we only use a 
single expert ($K=1$).

Model estimation/learning is performed by a dedicated expectation conditional 
maximization (ECM) algorithm by maximizing the observed data log-likelihood. 
We provide simulated examples to illustrate the use of the model in model-based
clustering of heterogeneous regression data and in fitting non-linear 
regression functions.

It was written in R Markdown, using the [knitr](https://cran.r-project.org/package=knitr) 
package for production.

See `help(package="meteorits")` for further details and references provided by
`citation("meteorits")`.

# Application to a simulated dataset

## Generate sample

```{r}
n <- 500 # Size of the sample
alphak <- matrix(c(0, 8), ncol = 1) # Parameters of the gating network
betak <- matrix(c(0, -2.5, 0, 2.5), ncol = 2) # Regression coefficients of the experts
sigmak <- c(0.5, 0.5) # Standard deviations of the experts
nuk <- c(5, 7) # Degrees of freedom of the experts network t densities
x <- seq.int(from = -1, to = 1, length.out = n) # Inputs (predictors)

# Generate sample of size n
sample <- sampleUnivTMoE(alphak = alphak, betak = betak, sigmak = sigmak, 
                         nuk = nuk, x = x)
y <- sample$y
```

## Set up tMoE model parameters

```{r}
K <- 2 # Number of regressors/experts
p <- 1 # Order of the polynomial regression (regressors/experts)
q <- 1 # Order of the logistic regression (gating network)
```

## Set up EM parameters

```{r}
n_tries <- 1
max_iter <- 1500
threshold <- 1e-5
verbose <- TRUE
verbose_IRLS <- FALSE
```

## Estimation

```{r}
tmoe <- emTMoE(X = x, Y = y, K, p, q, n_tries, max_iter, 
               threshold, verbose, verbose_IRLS)
```

## Summary

```{r}
tmoe$summary()
```

## Plots

### Mean curve

```{r}
tmoe$plot(what = "meancurve")
```

### Confidence regions

```{r}
tmoe$plot(what = "confregions")
```

### Clusters

```{r}
tmoe$plot(what = "clusters")
```

### Log-likelihood

```{r}
tmoe$plot(what = "loglikelihood")
```

# Application to a real dataset

## Load data

```{r}
library(MASS)
data("mcycle")
x <- mcycle$times
y <- mcycle$accel
```

## Set up tMoE model parameters

```{r}
K <- 4 # Number of regressors/experts
p <- 2 # Order of the polynomial regression (regressors/experts)
q <- 1 # Order of the logistic regression (gating network)
```

## Set up EM parameters

```{r}
n_tries <- 1
max_iter <- 1500
threshold <- 1e-5
verbose <- TRUE
verbose_IRLS <- FALSE
```

## Estimation

```{r}
tmoe <- emTMoE(X = x, Y = y, K, p, q, n_tries, max_iter, 
               threshold, verbose, verbose_IRLS)
```

## Summary

```{r}
tmoe$summary()
```

## Plots

### Mean curve

```{r}
tmoe$plot(what = "meancurve")
```

### Confidence regions

```{r}
tmoe$plot(what = "confregions")
```

### Clusters

```{r}
tmoe$plot(what = "clusters")
```

### Log-likelihood

```{r}
tmoe$plot(what = "loglikelihood")
```