---
title: "Introduction to the transitionPlot (deprecated)"
author: "Max Gordon"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to the transitionPlot (deprecated)}
  %\VignetteEngine{knitr::rmarkdown}
  %\usepackage[utf8]{inputenc}
---

Introduction
============

The transitionPlot function aims at illustrating the transition between classes. The original intent was to show how [self-administered the Charnley classification](https://www.tandfonline.com/doi/full/10.3109/17453674.2014.931199) behaves before and after surgery. The plot is a fancier version than what can be achieved using packages such as [*diagram*](https://CRAN.R-project.org/package=diagram) but at the cost of flexibility. The current function only allows to show a transition from one state to the next. 

**Note**: The new Transition class will superseed the transitionPlot. See `vignette("Introduction to the Transition-class")` for more info.

Generate some data
==================


We will start by simulating some data similar to my article. Each observation has a sex and a Charnley class (A, B, or C). The transition is then dependent on both the sex and the Charnley class.

```{r}
set.seed(1)
library(magrittr)
n <- 100
data <- 
  data.frame(
    Sex = sample(c("Male", "Female"),
                 size = n,
                 replace = TRUE),
    Charnley_class = sample(c("A", "B", "C"), 
                            size = n, 
                            replace = TRUE))
prob <- data.frame(
  A = 1/3 +
    (data$Sex == "Male") * .25 +
    (data$Sex != "Male") * -.25 +
    (data$Charnley_class %in% "B") * -.5 +
    (data$Charnley_class %in% "C") * -2 ,
  B = 1/3 +
    (data$Sex == "Male") * .1 + 
    (data$Sex != "Male") * -.05 +
    (data$Charnley_class == "C") * -.5,
  C = 1/3 +
    (data$Sex == "Male") * -.25 +
    (data$Sex != "Male") * .25)

# Remove negative probabilities
prob <- t(apply(prob, 1, function(x) {
  if (any(x < 0)){
    x <- x - min(x) + .05
    }
  x
  }))

data$Charnley_class_after <- 
  apply(prob, 1, function(p)
    sample(c("A", "B", "C"), 
           size = 1, 
           prob = p)) %>%
  factor(levels = c("A", "B", "C"))

# Create the transition matrix that 
# is the basis for the transition plot
trn_mtrx <-
  with(data,
       table(Charnley_class, 
             Charnley_class_after))
  
rm(prob)
```

Basic use
=========
```{r, echo=FALSE, }
knitr::opts_chunk$set(message=FALSE, 
                      warnings=FALSE)
```

The most simple use is to just supply the output from the `table()` call:

```{r, echo=FALSE}
knitr::opts_chunk$set(fig.height = 5, fig.width=5)
```

```{r}
library(Gmisc)
transitionPlot(trn_mtrx)
```

The out of the box arrows are rather in my opinion not well suited and I have therefore developed a few alternatives:

```{r}
transitionPlot(trn_mtrx, 
               type_of_arrow = "simple")
```

And a fancy variant that I call *gradient* arrows as they have a colored gradient inside that fades into the arrow color:

```{r}
transitionPlot(trn_mtrx, 
               type_of_arrow = "gradient")
```

Labels and stuff
================

```{r, echo=FALSE}
knitr::opts_chunk$set(fig.height = 6)
```

Adding title, box labels, and customizing box text can easily be done using the `main`, `box_label`, and `box_txt`. If you provide the `box_txt` a vector it assumes the same text for both left and right boxes but you can also have separate texts as in the example below:

```{r}
output_perc <- 
  function(txt, n) sprintf("%s\n[%.0f%%]", txt, n)
box_txt <- 
  cbind(mapply(output_perc, 
               txt = c("A", "B", "C"), 
               n = prop.table(rowSums(trn_mtrx))*100),
        mapply(output_perc, 
               txt = c("A", "B", "C"), 
               n = prop.table(colSums(trn_mtrx))*100))
transitionPlot(trn_mtrx, 
               main = "Charnley class changess",
               box_label = c("Before", "After"),
               box_txt = box_txt,
               cex = 1.2,
               type_of_arrow = "simple")
```

Using 3D matrices
=================

```{r, echo=FALSE}
knitr::opts_chunk$set(fig.height = 5.5)
```

We can enhance the [data-ink ratio](https://infovis-wiki.net/wiki/Data-Ink_Ratio) by adding a color split for the boxes. This works only for factors with 2 levels such as sex in our example.

```{r}
trn_mtrx_3D <-
  with(data,
       table(Charnley_class, 
             Charnley_class_after,
             Sex))

transitionPlot(trn_mtrx_3D, 
               fill_start_box = c("#5C246E", "#00688B"),
               type_of_arrow = "simple")
```

The gradient arrow is most useful in this setting. It mixes the two colors according to the particular transition composition and adds an explaining gradient bar:

```{r}
transitionPlot(trn_mtrx_3D, 
               fill_start_box = c("#5C246E", "#00688B"),
               type_of_arrow = "gradient")
```

Mixed text colors can be useful when one background color is brighter and white text becomes unreadable:

```{r}
transitionPlot(trn_mtrx_3D, 
               txt_start_clr = c("white", "black"),
               fill_start_box = c("#5C246E", "#BFEFFF"),
               type_of_arrow = "gradient")
```